package org.example.exampreparationtreasure.service;

import org.example.exampreparationtreasure.model.entity.Question;
import org.example.exampreparationtreasure.model.vo.StudyPlanResponse;
import org.example.exampreparationtreasure.model.vo.RecommendationHistoryResponse;
import org.example.exampreparationtreasure.model.vo.PreferenceRequest;

import java.util.List;

/**
 * 推荐系统服务接口
 */
public interface RecommendationService {

    /**
     * 获取推荐题目
     * @param userId 用户ID
     * @param includeCategoryIds 包含的分类ID列表
     * @param size 推荐数量
     * @return 推荐题目列表
     */
    List<Question> getRecommendedQuestions(Long userId, List<Long> includeCategoryIds, Integer size);

    /**
     * 根据用户偏好获取推荐题目（带难度过滤）
     * @param userId 用户ID
     * @param includeCategoryIds 包含的分类ID列表
     * @param difficultyLevel 难度级别（支持中英文）
     * @param size 推荐数量
     * @return 推荐题目列表
     */
    List<Question> getRecommendedQuestionsWithPreference(Long userId, List<Long> includeCategoryIds, 
                                                         String difficultyLevel, Integer size);

    /**
     * 生成个性化学习计划
     * @param userId 用户ID
     * @return 学习计划
     */
    StudyPlanResponse generateStudyPlan(Long userId);

    /**
     * 更新用户推荐偏好
     * @param userId 用户ID
     * @param preference 偏好设置
     */
    void updateUserPreference(Long userId, PreferenceRequest preference);

    /**
     * 获取推荐历史
     * @param userId 用户ID
     * @return 推荐历史
     */
    RecommendationHistoryResponse getRecommendationHistory(Long userId);

    /**
     * 记录推荐历史
     * @param userId 用户ID
     * @param questions 推荐的题目列表
     */
    void recordRecommendationHistory(Long userId, List<Question> questions);
}

